Skip to main content

Bill Payment V2

The Bill Payment V2 API allows clients to initiate bill payment transactions through the RPPS (Real-time Payments Processing System) using supported channels (e.g., Mastercard). This version introduces enhanced transaction details, biller metadata, and improved response payloads for reconciliation and audit purposes.

Method: POST​

{{URL}}/rpc/paymentv2

Example​

Request Parameters
ParameterDescription
method
Mandatory		String
Constant value – "billpay.transfer"
id
Mandatory		String
Unique ID of API request
Sample value – "1"
params
Mandatory		Object
payload
Mandatory		Object
channel
Mandatory		String
Payment channel through which the transaction is processed
Sample value – "MASTER_CARD"
source
Mandatory		String
Payment source system
Sample value – "RPPS"
transactionType
Mandatory		String
Type of transaction
Constant value – "BILLPAY_V2"
reference
Mandatory		String
Unique reference ID of the transaction
Sample value – "R90987895"
transactionDateTime
Optional		String
Transaction initiation date/time (YYYY-MM-DD HH:MM:SS)
Sample value – "2021-01-19 06:20:25"
reason
Optional		String
Purpose of the transaction
Sample value – "Bill Settlement for mycashrewards"
transactionAmount
Mandatory		Object
amount
Mandatory		String
Amount of the transaction
Sample value – "200"
currency
Mandatory		String
Type of currency used
Sample value – "USD"
debtorAccount
Mandatory		Object
identificationType
Mandatory		String
Type of account identifier
Sample value – "ACCOUNT_NUMBER"
identification
Mandatory		String
Debtor account number
Sample value – "200000000852262"
creditor
Mandatory		Object
userType
Mandatory		Type of creditor
Constant Value : "BILLER"
firstName
Optional		First name of biller contact.
Sample Value : "Ashley Stewart"
billerId
Mandatory		Unique biller identifier.
Sample Value : "3337333700"
billerName
Mandatory		Name of the biller.
Sample Value : "united Electric Cooperative Services Inc"
billerType
Mandatory		Type of creditor
Sample Value : "Core"
identificationType
Mandatory		String
Type of identification
Sample Value : "ACCOUNT_NUMBER"
identification
Mandatory		String
Biller account number.
Sample Value : "124-682"
api
Mandatory		Object
credential

Mandatory		String
Basic (space) [("<Username>:<apiKey>") as Base64 encoded value] to be provided
Sample Value: "Basic bmF2eWEubitlbXBAbmV0eGQuY29tOmY1OWIwY2NlOTU4ZTQ1YTc4MGVhZWIzYWVjOWVjZDAx"
signature

Mandatory		String
Sign the request payload (params.payload) using private key.
Sample Value: "MEQCIAbpxHpdOyBEVlmxPYv7m4Z1OvWJJYw7g7u3GE3T9nmvAiBjKHckSvb1M6O4t7FeWsn2z9Y3dMeYn3HyX/k28ek/Dw=="
apiKey

Optional		String
API key is provided at the time of device registration.
Sample Value : "f59b0cce958e45a780eaeb3aec9ecd01"

Body​



   {
  "method": "billpay.transfer",
  "id": "1",
  "params": {
    "payload": {
      "channel": "MASTER_CARD",
      "source": "RPPS",
      "transactionType": "BILLPAY_V2",
      "reference": "REF_V2_100008",
      "transactionDateTime": "2024-12-04 13:30:23",
      "reason": "Bill Settlement for mycashrewards",
      "transactionAmount": {
        "amount": "100",
        "currency": "USD"
      },
      "debtorAccount": {
        "identification": "200686362505215",
        "identificationType": "ACCOUNT_NUMBER"
      },
      "creditor": {
        "userType": "BILLER",
        "firstName": "Ashley Stewart",
        "billerId": "3337333700",
        "billerName": "united Electric Cooperative Services Inc",
        "billerType": "Core",
        "identification": "124-682",
        "identificationType": "ACCOUNT_NUMBER"
      }
    },
    "api": {
      "credential": "{{Credential}}",
      "signature": "{{signature}}",
      "apiKey": "{{ApiKey}}"
    }
  }
}



Response: 200​

Response Parameters
ParameterDescription
idString
Response ID echoed from the request
Sample Value : "1"
resultObject
Container for response data
apiObject
Contains API-specific transaction metadata
typeString
Type of API response
Sample Value : "BILLPAY_V2_ACK"
referenceString
Reference ID for the transaction
Sample Value : "REF1000001006"
dateTimeString
Date and time of transaction acknowledgement
Sample Value : "2025-06-04 13:09:03"
accountIdString
Debtor Account identifier
Sample Value : "200686362505215"
balanceCentsNumber
Available balance in cents.
Sample Value : 115384
holdBalanceCentsNumber
Amount on hold in cents
Sample Value : 100
statusString
Status of the account
Valid values:
- ACTIVE: The account is open for all transactions.
- DORMANT: Only inbound credit transactions are allowed. The account will automatically transition to Active when an inbound credit transaction occurs.
- SUSPENDED: No transactions are allowed in this state. The account must be manually changed to Active, typically due to compliance issues. It can also be reactivated based on a court order.
- CLOSED: The account is permanently closed, and no transactions are allowed. Once an account is in this state, it cannot be reactivated.
Sample Value : "ACTIVE"
transactionNumberString
Unique transaction number assigned
Sample Value : "QA00000003108005"
transactionStatusString
Status of the transaction
Sample Value : "PENDING"
transactionAmountCentsNumber
Transaction amount in cents
Sample Value : 500
originalRequestBase64String
Original request in Base64 encoded format
processIdString
Unique process ID for end-to-end tracking
Sample Value : "PL25060403017005"
headerObject
Header metadata for validation and logging
referenceString
Transaction reference.
Sample Value : "REF1000001006"
signature

Mandatory		String
Sign the request payload (params.payload) using private key.
Sample Value: "MEYCIQC29ySJAaiLEPY8+jfTR12p7w6fag2LEzd9ei/4M0UZtgIhAMV3i2XuHWzZ3FkIonlMxnBLBAu9QPiA5c75OkOX0P+O"
apiKey

Optional		String
API key is provided at the time of device registration.
Sample Value : "f59b0cce958e45a780eaeb3aec9ecd01"

{
  "id": "1",
  "result": {
    "api": {
      "type": "BILLPAY_V2_ACK",
      "reference": "REF_V2_100008",
      "dateTime": "2025-08-08 15:54:25"
    },
    "account": {
      "accountId": "200686362505215",
      "balanceCents": 203624,
      "holdBalanceCents": 300,
      "status": "ACTIVE"
    },
    "transactionNumber": "QA00000003387002",
    "transactionStatus": "COMPLETED",
    "transactionAmountCents": 100,
    "originalRequestBase64": "eyJjaGFubmVsIjoiTUFTVEVSX0NBUkQiLCJ0cmFuc2FjdGlvblR5cGUiOiJCSUxMUEFZX1YyIiwidHJhbnNhY3Rpb25EYXRlVGltZSI6IjIwMjQtMTItMDQgMTM6MzA6MjMiLCJyZWZlcmVuY2UiOiJSRUZfVjJfMTAwMDA4IiwicmVhc29uIjoiQmlsbCBTZXR0bGVtZW50IGZvciBteWNhc2hyZXdhcmRzIiwidHJhbnNhY3Rpb25BbW91bnQiOnsiYW1vdW50IjoiMTAwIiwiY3VycmVuY3kiOiJVU0QifSwiZGVidG9yQWNjb3VudCI6eyJpZGVudGlmaWNhdGlvbiI6IjIwMDY4NjM2MjUwNTIxNSIsImlkZW50aWZpY2F0aW9uVHlwZSI6IkFDQ09VTlRfTlVNQkVSIn0sImNyZWRpdG9yIjp7InVzZXJUeXBlIjoiQklMTEVSIiwiaWRlbnRpZmljYXRpb24iOiIxMjQtNjgyIiwiaWRlbnRpZmljYXRpb25UeXBlIjoiQUNDT1VOVF9OVU1CRVIiLCJiaWxsZXJJZCI6IjMzMzczMzM3MDAiLCJiaWxsZXJOYW1lIjoidW5pdGVkIEVsZWN0cmljIENvb3BlcmF0aXZlIFNlcnZpY2VzIEluYyIsImJpbGxlclR5cGUiOiJDb3JlIn19",
    "processId": "PL25080803295002"
  },
  "header": {
    "reference": "REF_V2_100008",
    "apiKey": "0357862f1a984778a4d584a6c0ca3273",
    "signature": "MEUCIBz9I3ZC/po9XO6sLXjYYaTheuw7MoBxy+JgwBQJQCsEAiEAmLVwRnQEE8BOIl4PWiuI9UQ3jOzHjOUaQ17z1kc4bOA="
  }
}



Status Codes​

CodeMeaning
COMPLETEDTransaction successfully processed.
FAILEDTransaction was rejected or failed during processing.
PENDINGTransaction is still being processed.

Error Codes​

Error Codes
Error CodeError Message
A107DUPLICATE_REFERENCE
A112INVALID_AMOUNT
A113INVALID_CHANNEL
A114CUSTOMER_NOT_FOUND
A116INVALID_API_KEY
A118TRANSACTION_REFERENCE_EMPTY
A122PROGRAM NOT FOUND
A123CREDITOR_ACCOUNT_TYPE_EMPTY
A126TRANSACTION_TYPE_EMPTY
A147TRANSACTION NOT FOUND
A157INVALID ACCOUNT NUMBER
A161DEBTOR ACCOUNT NOT FOUND
A166DEBTOR_ACCOUNT_TYPE_EMPTY
A167DEBTOR_ACCOUNT_ID_EMPTY
A169ACCOUNT NUMBER DOES NOT MATCH WITH API KEY
A172IDENTIFICATIONTYPE2 SHOULD BE EITHER SAVINGS OR CHECKING
A183PAYLOAD EMPTY
A184INVALID ORIGINAL TRANSACTION STATUS
A185TRANSACTION ALREADY REVERSED
A186CREDITOR FIRSTNAME REQUIRED
A187CREDITOR POSTAL ADDRESS ADDRESSLINE1 REQUIRED
A188CREDITOR POSTAL ADDRESS ZIPCODE REQUIRED
A189CREDITOR POSTAL ADDRESS COUNTRYCODE REQUIRED
A190CREDITOR CONTACT EITHER PRIMARYEMAIL OR PRIMARYPHONE REQUIRED
A191DEBTOR FIRSTNAME REQUIRED
A192DEBTOR POSTAL ADDRESS ADDRESSLINE1 REQUIRED
A193DEBTOR POSTAL ADDRESS ZIPCODE REQUIRED
A194DEBTOR POSTAL ADDRESS COUNTRYCODE REQUIRED
A195DEBTOR CONTACT EITHER PRIMARYEMAIL OR PRIMARYPHONE REQUIRED
A196DEBTOR USERTYPE REQUIRED
A197DEBTOR IDENTIFICATION REQUIRED
A198DEBTOR IDENTIFICATIONTYPE REQUIRED
A199CREDITOR USERTYPE REQUIRED
A200CREDITOR IDENTIFICATION REQUIRED
A201CREDITOR IDENTIFICATIONTYPE REQUIRED
A205INVALID_PROGRAM
A206INVALID_PRODUCT
A207PRODUCT_PROGRAM_CHANNEL SETTING NOT FOUND
A208ID EMPTY
A209APIKEY NOT FOUND
1111CREDITOR ACCOUNT NOT FOUND
1113CREDITOR NOT FOUND
1116TRANSACTION AMOUNT NOT FOUND
1117TRANSACTION CURRENCY NOT FOUND
1122CREDITOR ACCOUNT IDENTIFICATION TYPE NOT FOUND
1123CREDITOR ACCOUNT IDENTIFICATION TYPE2 NOT FOUND
1126DEBTOR ACCOUNT IDENTIFICATION TYPE NOT FOUND
1127PRODUCT NOT FOUND
1128PROGRAM NOT FOUND
1129CHANNEL NOT FOUND
1130TRANSACTION TYPE NOT FOUND
1131INVALID API KEY
2053INVALID_ACCOUNT_NUMBER
5019INSUFFICIENT BALANCE
9999INTERNAL ERROR
1001CARD HOLDER ALREADY EXISTS
1002INVALID CARDHOLDER FIRST NAME
1003INVALID CARDHOLDER PHONE NUMBER
1004INVALID CARDHOLDER ADDRESS LINE 1
1005INVALID CARDHOLDER CITY
1006INVALID CARDHOLDER STATE
UNAUTHORIZEDAccess Denied
INVALID_SIGNATUREInvalid Signature
NOT_FOUND_USER_DEVICEUser device not found
BAD_CREDENTIALInvalid Credential